Inside Macintosh: QuickTime /

Chapter 2 - Movie Toolbox / Movie Toolbox Reference

Functions for Editing Movies / Adding Samples to Media Structures

GetMediaSample

The GetMediaSample function returns a sample from a movie data file. You add samples to movie data files with the AddMediaSample function (described on page 2-256).

pascal OSErr GetMediaSample (Media theMedia, Handle dataOut, 
                     long maxSizeToGrow, long *size, 
                     TimeValue time, TimeValue *sampleTime, 
                     TimeValue *durationPerSample, 
                     SampleDescriptionHandle sampleDescriptionH, 
                     long *sampleDescriptionIndex, 
                     long maxNumberOfSamples, 
                     long *numberOfSamples, 
                     short *sampleFlags); 

theMedia

Specifies the media for this operation. Your application obtains this media identifier from such Movie Toolbox functions as NewTrackMedia and GetTrackMedia (described on page 2-138 and page 2-190, respectively).

dataOut

Contains a handle. The GetMediaSample function returns the sample data into this handle. The function increases the size of this handle, if necessary. You can specify the handle's maximum size with the maxSizeToGrow parameter.

maxSizeToGrow

Specifies the maximum number of bytes of sample data to be returned. The GetMediaSample function does not increase the handle specified by the dataOut parameter to a size greater than you specify with this parameter. Set this value to 0 to enforce no limit on the number of bytes to be returned.

size

Contains a pointer to a long integer. The GetMediaSample function updates the field referred to by the size parameter with the number of bytes of sample data returned in the handle specified by the dataOut parameter. Set this parameter to nil if you are not interested in this information.

time

Specifies the starting time of the sample to be retrieved. You must specify this value in the media's time scale.

sampleTime

Contains a pointer to a time value. The GetMediaSample function updates this time value to indicate the actual time of the returned
sample data. If you are not interested in this information, set this parameter to nil.

The returned time may differ from the time you specified with the time parameter. This will occur if the time you specified falls in the middle of a sample.

durationPerSample

Contains a pointer to a time value. The Movie Toolbox returns the duration of each sample in the media. This time value is expressed in the media's time scale. Set this parameter to 0 if you do not want this information.

sampleDescriptionH

Contains a handle to a sample description. The GetMediaSample function returns the sample description corresponding to the returned sample data. The function resizes this handle as appropriate. If you do not want the sample description, set this parameter to nil.

sampleDescriptionIndex

Contains a pointer to a long integer. The GetMediaSample function returns an index value to the sample description that corresponds to
the returned sample data. If you do not want this information, set this parameter to nil.

You can use this index to retrieve the sample description by calling the GetMediaSampleDescription function, which is described on page 2-210.

You can retrieve the sample description itself by using the sampleDescriptionH parameter.

maxNumberOfSamples

Specifies the maximum number of samples to be returned. The Movie Toolbox does not return more samples than you specify with this parameter.

If you set this parameter to 0, the Movie Toolbox uses a value that is appropriate for the media, and returns that value in the field referenced by the numberOfSamples parameter.

numberOfSamples

Contains a pointer to a long integer. The GetMediaSample function updates the field referred to by this parameter with the number of samples it actually returns. If you do not want this information, set this parameter to nil.

sampleFlags

Contains a pointer to a short integer. The GetMediaSample function returns flags that describe the sample. The following flag is available (set unused flags to 0):

mediaSampleNotSync

Indicates that the sample that is returned is not a sync sample. Set this flag to 1 if the sample is not a sync sample. Set this flag to 0 if the sample is a sync sample.

If you do not want this information, set this
parameter to nil.

ERROR CODES

invalidMedia

-2008

This media is corrupted or invalid

File Manager errors
Memory Manager errors